home *** CD-ROM | disk | FTP | other *** search
/ Deutsche Edition 1 / Deutsche Edition 1.iso / amok / 031-040 / amok37 / headerinfo < prev    next >
Text File  |  1993-11-04  |  11KB  |  325 lines
  1. ======================================================================
  2.                 AMOK - Amiga Modula Klub Stuttgart
  3.  
  4.                  Standard Identifier für ProgInfo
  5.            (Dokumentationsextraktion aus dem Quelltext)
  6. ======================================================================
  7.  
  8.  
  9. Programmkopf
  10.  
  11. Für alle AmokProgramme ist ein Programmkopf vorgeschrieben, der die
  12. wichtigsten Informationen zu diesem enthält.
  13. Bei Modula-2-Programmen muß er vor dem Schlüsselwort MODULE in einem
  14. Kommentar stehen. Er sollte durch "***"- oder "---"-Zeilen hervorgehoben
  15. sein, ein Einrahmen ist jedoch nicht zweckmäßig (da die letzten "*"s in
  16. der Zeile stören).
  17. Der Programmkopf enthält mehrere Einträge, die jeweils mit
  18. ":"Schlüsselwort"." beginnen. Reicht eine Zeile für einen Eintrag nicht
  19. aus, wird das ":"Schlüsselwort"." in der nächsten Zeile wiederholt und
  20. der Eintrag danach fortgesetzt. Doppelpunkt, Punkt und Schreibweise
  21. sind wichtig, da sonst die Einträge von Doku-Extraktionsprogrammen nicht
  22. gefunden werden.
  23.  
  24. Der Programmkopf muß (!) mindestens folgende Einträge enthalten:
  25.  
  26. :Program.       <Programmname>
  27. :Contents.      <Kurzbeschreibung von Inhalt/Verwendungszweck>
  28. :Author.        <voller Autorenname, kein Pseudonym (!)>
  29. :Copyright.     <Bemerkung über Copyright oder Public Domain>
  30. :Language.      <Sprache, eventuell Bemerkung über Besonderheiten>
  31. :Translator.    <Name des Compilers/Assemblers mit Versionsangabe>
  32. :History.       <Version, Datum, Autor, Bemerkung>
  33.  
  34. Falls notwendig müssen auch folgende Angaben gemacht werden:
  35.  
  36. :Support.       <Hinweis auf von anderen übernomene Programmteile/Ideen>
  37. :Imports.       <Importierte Module außer dem Standardumfang des Compilers>
  38. :Bugs.          <bekannte Fehler>
  39.  
  40. Freiwillig sind diese Angaben:
  41.  
  42. :Address.       <Adresse des Autors>
  43. :Phone.         <seine Telephonnummer>
  44. :Update.        <Angaben über Änderungen, die :History. nicht abdeckt>
  45. :Remark.        <beliebiger Kommentar>
  46. :Usage.         <Usage zB. für CLI-Befehl>
  47.  
  48. Andere Einträge Date, Shortcut, Version sind möglichst nicht mehr zu
  49. benutzen. Fehlende Einträge sollten so bald und gut als möglich
  50. nachgetragen oder rekonstruiert werden.
  51.  
  52.  
  53. Empfehlungen
  54.  
  55. Auf eine strikte festlegung des Programmkopftextes wurde verzichtet. Damit
  56. dieser jedoch einigermaßen einheitlich bleibt sollte man die folgenden
  57. Regeln beachten.
  58.  
  59. Leere Einträge
  60.  
  61. Außer den zuerst genannten Pflichteinträgen können eventuell auch welche
  62. entfallen. Am besten läßt man dann den gesammten Eintrag sammt Schlüssel-
  63. wort weg. Als leer gelten außerdem Einträge, die nur aus Leerzeichen,
  64. Sternchen "*" oder Strichen "-" bestehen.
  65. Unsinnige Einträge (zB. ":Imports. bis jetzt noch nichts") sind möglichst
  66. zu unterlassen.
  67.  
  68. :Program.
  69.  
  70. Hier sollte der Programmname stehen, der mit dem Filenamen (mit Extension,
  71. zB. "Test.def") übereinstimmen sollte. Reicht der Programmname zur
  72. eindeutigen Indentifizierung nicht aus (z.B. geändertes Modul "Strings")
  73. so steht hinter dem Programmnamen ein entsprechender Kommentar.
  74.  
  75. :Contents.
  76.  
  77. Kurzbeschreibung von Programminhalt und -funktion. Die Beschreibung
  78. sollte erklärend sein und nicht nur eine längere Version des Programm-
  79. namens sein (zB.  N I C H T :
  80.  :Program.  InOut.def
  81.  :Contents. Definitionsmodul Input/Output
  82. ).
  83.  
  84. :Author.
  85.  
  86. Bitte den vollen Namen angeben. Pseudonyme sind unzulässig.
  87. Ein Programm kann auch mehere Autoren haben, z.B. wenn ein PC-Programm
  88. auf den Amiga umgesetzt wurde.
  89.  
  90. :Address.
  91.  
  92. Freiwillig ist die Angabe der Adresse des Autors. Sie sollte Straße,
  93. Hausnummer, Postleitzahl, Ort und Land enthalten.
  94.  
  95. :Phone.
  96.  
  97. Telefonnummer des Autors mit Vorwahl. Zusätzliche Bemerkungen, zB. Zeit-
  98. angaben für Erreichbarkeit, sind zulässig. Hat ein Programm mehere Autoren
  99. (s. oben) so steht hier die Telefonnummer des für dieses Programm
  100. zuständigen Autors, d.h. desjenigen, der eventuelle Fragen am besten
  101. beantworten kann.
  102.  
  103. :Copyright.
  104.  
  105. Hieraus sollte ersichtlich sein, ob das Programm frei kopiert werden
  106. darf (Public Domain), ob eine (Shareware-)Gebühr verlangt wird oder
  107. ob das Programm gar nicht weitergegeben werden darf.
  108. Kommentare wie zB. "copy it, but leave my name in" oder ähnliches sind
  109. zulässig. Bei längeren "Plädoyers" sollte allerdings auf eine extra
  110. Datei verwiesen werden.
  111.  
  112. :Language.
  113.  
  114. Hier steht im Normalfall "Modula-2". Wenn das Programm INLINE-Assembler-
  115. code enthält, sollte dies hier Vermerkt werden. Ebenso sollte verfahren
  116. werden, wenn das Programm dem Modula-Standard nicht entsprechende
  117. Statements enthält. Dazu gehört unter anderem die seit Version 3.2
  118. mögliche Typenkonversion von ADDRESS/BPTR und die Dereferenzierung
  119. von BPTRn (Zugriff auf BcplPtr^.items). Die normale Verwendung des
  120. Typs BPTR als opaker Typ gehört nicht dazu, denn er ist im Standard-
  121. Modula erlaubt.
  122. Der Sinn hiervon ist es, Leute zu warnen, die Programme auf andere
  123. Compiler umsetzen wollen.
  124.  
  125. :Translator.
  126.  
  127. Bezeichnet den Compiler (/Assembler/Interpreter) (normal M2Amiga A+L)
  128. und die Versionsnummer (V3.2d oder V3.1d). Dahinter stehen eventuelle
  129. Hinweise auf Compiler-Bugs, die für dieses Programm relevant sind.
  130.  
  131. :History.
  132.  
  133. Dies ist einer der wichtigsten Einträge. Er beinhaltet Informationen
  134. über die Versionen des Programms (Opfer), der entsprechenden
  135. Erstellungs- und Änderungsdaten (Tatzeit), den Autor oder für die
  136. Änderung Veratwortlichen (Täter) sowie eine optionale Bemerkung
  137. (Motiv). Beispiel:
  138.  
  139. :History.       V1.1 [bne] 29.Mar.1989 (bug in Init() fixed)
  140.  
  141. Den Versionsnummern wird später noch ein spezielles Kapitel gewidmet.
  142. Zusammengehörige Definitions- und Implementationsmodule tragen immer
  143. mindestens gleiche Versionsnummer (Revisionsnummer, Branchnummer und
  144. Kennbuchstabe dürfen verschieden sein).
  145. Das Datum besteht aus dem ein- oder zweistelligen Tag, dem Monats-
  146. kürzel (Jan,Feb,Mar,Apr,May,Jun,Jul,Aug,Sep,Oct,Nov,Dez) aus drei
  147. Buchstaben und der zwei oder vierstelligen Jahreszahl. Für den Autor
  148. steht ein Kürzel (für Klubmitglieder) oder der Nachname für andere.
  149.  
  150. :Support.
  151.  
  152. Der Fairneß halber sollte man hier Angaben über Beiträge anderer
  153. Personen machen, wenn man Schuldgefühle wegen geklauter Ideen oder
  154. Algorithmen hat.
  155.  
  156. :Imports.
  157.  
  158. Importiert das Modul außer den Standardmodulen des Compilers noch
  159. weitere, so müssen diese hier eingetragen werden. Wird eine bestimmte
  160. Version benötigt, folgt auf den Namen des importierten Moduls dessen
  161. Versionsnummer. Es dürfen auch Verweise auf Amok-Disks oder den Autor
  162. gemacht wedren. Beispiel:
  163.  
  164. :Imports.       MemSystem1.3 [bne], List [mif] Amok#7
  165.  
  166. :Bugs.
  167.  
  168. Sind Fehler eines Moduls bekannt, oder besteht der Verdacht, daß das
  169. Modul fehlerhaft ist, wird dies hier vermerkt. Soweit dies möglich
  170. ist, soll der Fehler möglichst eng eingegrenzt werden (z.B Angabe der
  171. Prozedur, in der er auftritt). Ist ein Modul noch nicht vollständig
  172. ausgetestet, sollte man mit ":Bugs. not tested" warnen. ":Bugs. none"
  173. verpflichtet zu mindestens 99,9% Fehlerfreiheit!
  174.  
  175. :Usage.
  176.  
  177. bezeichnet die Syntax eines CLI-Befehls und dessen Argumente.
  178. Die Usage wird entweder in EBNF oder mit dem vom Dos-Handbuch und
  179. ARP verwendeten Template angegeben.
  180.  
  181.  
  182. Versionsnummern
  183.  
  184. Die Versionsnummer besteht normalerweise aus zwei Stellen (version,
  185. revision), die durch einen Punkt getrennt sind. Die erste lauffähige
  186. Version wird mit 1.0 bezeichnet. Bei jeder Änderung wird die zweite Stelle
  187. (Revision) um eins erhöht, wobei nach 1.9 die 1.10 und dann 1.11 usw.
  188. folgt. Bei sehr tiefgreifenden Neuerungen wird die erste Stelle (Version)
  189. erhöht, die zweite (Revision) springt auf 0. Die Versionsnummer darf
  190. NICHT als Dezimalbruch angesehen werden, der sich jedesmal um 1/10 erhöht.
  191. Eine Revision ist KEINE zehntel Version und eine Version entspricht
  192. NICHT 10 Revisions. Version und Revision werden unabhängig gezählt !!!
  193. Versionsnummern wie 1.09 sind unzulässig und 1.10 (erste Version, zehnte
  194. Revision) steht zwischen 1.9 und 1.11 und ist nicht gleich 1.1 !
  195. "Hundertstel" Versionen gibt es nicht. Wenn es erforderlich wird, eine
  196. Version nachträglich in eine Reihe einzufügen, wird dies durch eine zweiten
  197. Punkt gekennzeichnet. Beispiel: Es existieren bereits die Versionen 1.0 bis
  198. 1.4 , und jemand ändert nachträglich die Version 1.2  . Diese bekommt dann
  199. die Nummer 1.2.1 (sog. Branch-Version). Man kann Versionsreihen auch als
  200. Baum darstellen:
  201.  
  202.       1.0
  203.  
  204.        |
  205.        V
  206.  
  207.       1.1
  208.  
  209.        |
  210.        V
  211.  
  212.       1.2
  213.  
  214.        |
  215.       / \
  216.      /   \
  217.     V     V
  218.  
  219.    1.3   1.2.1
  220.  
  221.     |      |
  222.     V      V
  223.  
  224.    1.4    1.2.2
  225.  
  226.     |      usw.
  227.  
  228.    ...
  229.  
  230.     |
  231.     V
  232.  
  233.    1.9
  234.  
  235.     |
  236.     V
  237.  
  238.    1.10
  239.  
  240.    usw.
  241.  
  242.  
  243. Die Zählweise entspricht nicht der von Big Blue, verleitet aber dafür zu
  244. weniger Mißverständnissen, weil man nicht rätseln muß, ob 3.2 jetzt die auf
  245. 3.1 oder auf 3.19 folgende Version ist. Version und Revision können
  246. beliebig hoch werden - Beispiel: die Libraries der alten 1.2 Workbench
  247. trugen die Versionsnummer 33.180 (dreiunddreißigste Version,
  248. hundertachzigste Revision).
  249.  
  250. Wer noch eine feiner abgestufte Unterscheidung machen möchte, kann der
  251. Nummer noch einen Kleinbuchstaben anhängen. Dieser ist optional und muß
  252. nichts über die Reihenfolge aussagen (z.B. 3.2d für die deutsche und 3.2e
  253. für die englische Version).
  254.  
  255. Entsprechend dem Vorschlag von Bernd Preusing ist es jetzt doch zulässig,
  256. daß ein Implementationsmodul eine höhere Revisionsnummer hat wie das
  257. zugehörige Definitionsmodul. Dadurch ist es nicht nötig, wegen jeder
  258. Kleinigkeit das Definitionsmodul anzutasten, wodurch das Make viel Arbeit
  259. bekäme.
  260.  
  261.  
  262. Source-Code-Format
  263. ------------------
  264. Damit der Sourcecode einigermaßen übersichtlich ist, wird folgende
  265. Formatierung vorgeschlagen (nicht zwingend, nur übersichtlich muß es sein):
  266.  
  267. * In jeder Zeile steht nur eine logische Anweisungseinheit.
  268.  
  269. * Globale Prozeduren, Variablen und Konstanten stehen ganz am Anfang
  270.   der Zeile.
  271.  
  272. * Deklarationen und Prozedurkörper sind gegenüber ihrem CONST, VAR,
  273.   TYPE und PROCEDURE eingerückt.
  274.  
  275. * Programmteile, die lokal zu anderen definiert werden, oder von
  276.   bestimmten Konstrukten eingeschlossen werden, werden jeweils
  277.   relativ zu diesen um ZWEI Zeichen eingerückt.
  278.  
  279. * Zusammengehörende BEGIN und END, IF, ELSE und END usw. stehen jeweils
  280.   untereinander. Ist ein END mehr als eine Bildschirmseite (25 Zeilen)
  281.   von seinem BEGIN etc. entfernt, steht hinter dem END in Kommentar,
  282.   was dort beendet wurde.
  283.  
  284. * Außer nach VAR, CONST, TYPE, BEGIN, DO, THEN, LOOP, RETURN und EXIT
  285.   steht hinter jeder Zeile ein Semikolon.
  286.  
  287. * Elemente von Mengen, Aufzählungstypen und RECORDs fangen klein an,
  288.   Konstanten fangen klein oder groß an, alles andere immer groß.
  289.   Zusammengesetzte Wörter haben auch in der Mitte "GrossBuchstaben".
  290.  
  291. * Paßt die Parameterliste einer Prozedur nicht in eine Zeile
  292.   (75 Zeichen), werden die Parameter untereinander angeordnet.
  293.  
  294. * Importe werden alphabetisch nach den Namen der Module geordnet.
  295.   Sind Importlisten länger als zwei Zeilen werden auch die importierten
  296.   Objekte alphabetisch sortiert.
  297.  
  298. MODULE Beispiel;
  299.  
  300. CONST
  301.   welches=106;
  302.  
  303. PROCEDURE TuWas(    Dies:Typ;
  304.                 VAR Jenes:Art):BOOLEAN;
  305.   CONST
  306.     X=1;
  307.     Y=10;
  308.   VAR
  309.     Zähler:INTEGER;
  310.   BEGIN
  311.     FOR Zähler:=X TO Y DO
  312.       Action(Dies,Jenes);
  313.     END
  314.     RETURN Jenes=welches
  315.   END TuWas;
  316.  
  317. BEGIN
  318.   IF TuWas(etwas,irgendWas) THEN
  319.     Aktion1;
  320.   ELSE
  321.     Aktion2;
  322.   END;
  323. END Beispiel.
  324.  
  325.